Skip to content

gh-148770: Document quoting requirement for IMAP mailbox names with spaces#148785

Open
CodeLine9 wants to merge 2 commits into
python:mainfrom
CodeLine9:clawoss/docs/148770-imaplib-select-quoting
Open

gh-148770: Document quoting requirement for IMAP mailbox names with spaces#148785
CodeLine9 wants to merge 2 commits into
python:mainfrom
CodeLine9:clawoss/docs/148770-imaplib-select-quoting

Conversation

@CodeLine9
Copy link
Copy Markdown

@CodeLine9 CodeLine9 commented Apr 19, 2026 •
edited by github-actions Bot
Loading

The IMAP4.select() docs don't mention that mailbox names containing spaces must be quoted by the caller. Since _command() sends arguments as-is (no auto-quoting), a call like M.select('my important mail') sends the space-delimited name to the server, causing errors.

Added a note to the select() method documentation showing the correct usage: M.select('"my important mail"').

Fixes #148770.

📚 Documentation preview 📚: https://cpython-previews--148785.org.readthedocs.build/

@CodeLine9
pythongh-148770: Document quoting requirement for IMAP mailbox names …
60b03d2 
…with spaces

Add a note to IMAP4.select() documenting that mailbox names containing
spaces must be quoted by the caller, e.g. M.select('"my important mail"').
@CodeLine9 CodeLine9 requested a review from a team as a code owner April 19, 2026 23:24
@python-cla-bot
Copy link
Copy Markdown

python-cla-bot Bot commented Apr 19, 2026 •
edited
Loading

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Apr 19, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Apr 19, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Apr 19, 2026
Open
@read-the-docs-community
Copy link
Copy Markdown

read-the-docs-community Bot commented May 11, 2026

Documentation build overview

📚 cpython-previews | 🛠️ Build #32635870 | 📁 Comparing 32d0925 against main (8276778)

  🔍 Preview build  

126 files changed · + 3 added · ± 123 modified

+ Added

± Modified

@savagemechanic
Copy link
Copy Markdown
Contributor

savagemechanic commented May 17, 2026

I took a look at this while reading through the neighboring imaplib docs.

The note seems accurate for current main: IMAP4.select() passes the mailbox argument through _simple_command(), and _command() encodes str arguments to bytes and appends them directly. So a mailbox name containing spaces needs to be quoted by the caller today.

Given the related comment on #148770, I wonder whether this should be scoped only to select(), or whether the docs should mention the broader command-argument behavior. There are older/open threads about the general auto-quoting mismatch (#92835, #58148, and PR #6395), and the current docs still describe automatic quoting more generally.

So this PR looks useful as a targeted clarification, but maybe it should avoid sounding like select() is the only affected command.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

IMAPlib Lib/imaplib.py folders with spaces in their names

2 participants

@CodeLine9 @savagemechanic